/**
 * @file gameservice.h
 * @brief 游戏服务类头文件 - 处理游戏相关的业务逻辑
 *
 * GameService是应用程序的游戏管理核心，提供：
 * - 游戏服务器列表的获取和筛选
 * - 游戏会话的创建和管理
 * - 服务器状态的实时监控
 * - 游戏配置的解析和处理
 * - 最佳服务器的推荐算法
 */

#ifndef GAMESERVICE_H
#define GAMESERVICE_H

#include <QObject>          // Qt对象基类
#include <QJsonObject>      // JSON对象处理
#include <QJsonArray>       // JSON数组处理
#include <QStringList>      // 字符串列表
#include "apiclient.h"
#include "gameservicediscovery.h"

/**
 * @class GameService
 * @brief 游戏服务类
 *
 * 封装所有游戏相关的业务逻辑，提供完整的游戏服务器管理功能。
 * 通过ApiClient与后端游戏服务器通信，处理游戏的整个生命周期。
 */
class GameService : public QObject
{
    Q_OBJECT  // 启用Qt元对象系统

public:
    /**
     * @struct GameServer
     * @brief 游戏服务器信息数据结构
     *
     * 存储从服务器获取的完整游戏服务器信息，包括连接信息、状态和特性。
     * 这个结构体会从JSON响应中解析得到，用于UI显示和连接选择。
     */
    struct GameServer {
        QString serverId;               ///< 服务器唯一标识符
        QString name;                   ///< 服务器显示名称
        QString host;                   ///< 服务器主机地址（IP或域名）
        int port = 0;                   ///< 服务器端口号
        QString gameType;               ///< 游戏类型（snake、tetris、puzzle等）
        QString region;                 ///< 服务器地区（asia、europe、america等）
        QString status;                 ///< 服务器状态（online、offline、maintenance等）
        int maxPlayers = 0;             ///< 最大玩家数量
        int currentPlayers = 0;         ///< 当前在线玩家数量
        int ping = 0;                   ///< 延迟时间（毫秒）
        double loadPercentage = 0.0;    ///< 服务器负载百分比（0.0-100.0）
        QString version;                ///< 服务器游戏版本
        QStringList features;           ///< 服务器特性列表（如"ranked"、"casual"等）
        QString lastUpdated;            ///< 最后更新时间（ISO 8601格式）
    };

    /**
     * @struct GameLoginResult
     * @brief 游戏登录结果数据结构
     *
     * 存储成功加入游戏后服务器返回的会话信息，包括分配的服务器、
     * 会话令牌和游戏配置。用于建立游戏连接和管理游戏会话。
     */
    struct GameLoginResult {
        GameServer serverInfo;          ///< 分配的游戏服务器信息
        QString sessionToken;          ///< 游戏会话令牌（用于游戏服务器认证）
        QString sessionId;             ///< 会话唯一标识符
        int expiresIn = 0;             ///< 会话过期时间（秒）
        QJsonObject gameConfig;        ///< 游戏配置参数（JSON格式）
    };

    /**
     * @struct ServerSummary
     * @brief 服务器汇总统计数据结构
     *
     * 存储服务器列表的统计信息和分页信息，用于UI显示和分页控制。
     * 提供服务器整体状况的概览信息。
     */
    struct ServerSummary {
        int totalServers = 0;           ///< 总服务器数量
        int onlineServers = 0;          ///< 在线服务器数量
        int maintenanceServers = 0;     ///< 维护中服务器数量
        int totalPlayers = 0;           ///< 总在线玩家数量
        int totalCapacity = 0;          ///< 总服务器容量

        // === 分页信息 ===
        int currentPage = 1;            ///< 当前页码
        int totalPages = 1;             ///< 总页数
        int pageSize = 50;              ///< 每页大小
    };

    explicit GameService(QObject *parent = nullptr);
    explicit GameService(ApiClient *apiClient, QObject *parent = nullptr);

    // === 游戏操作 ===
    /**
     * @brief 获取游戏服务器列表（传统方式）
     * @param gameType 游戏类型
     * @param region 地区
     * @param status 服务器状态
     * @param sortBy 排序方式
     * @param limit 限制数量
     * @param offset 偏移量
     */
    void getGameServers(const QString &gameType = QString(),
                       const QString &region = QString(),
                       const QString &status = "online",
                       const QString &sortBy = QString(),
                       int limit = 50,
                       int offset = 0);

    /**
     * @brief 使用服务发现获取游戏服务器列表（推荐方式）
     * @param gameType 游戏类型
     * @param healthyOnly 是否只获取健康的服务
     */
    void discoverGameServices(const QString &gameType = QString(), bool healthyOnly = true);

    /**
     * @brief 加入游戏会话
     * @param gameType 游戏类型
     * @param serverPreference 服务器偏好
     */
    void joinGame(const QString &gameType, const QString &serverPreference = "balanced");

    /**
     * @brief 获取最佳游戏服务器
     * @param gameType 游戏类型
     * @param region 地区
     * @param limit 限制数量
     */
    void getBestServers(const QString &gameType, const QString &region = "asia", int limit = 5);

    // === 服务发现控制 ===
    /**
     * @brief 启用服务发现自动刷新
     * @param interval 刷新间隔（秒）
     */
    void enableServiceDiscoveryAutoRefresh(int interval = 30);

    /**
     * @brief 禁用服务发现自动刷新
     */
    void disableServiceDiscoveryAutoRefresh();

    /**
     * @brief 手动刷新服务发现
     */
    void refreshServiceDiscovery();

    // 支持的游戏类型
    static QStringList getSupportedGameTypes() {
        return {"snake", "tetris", "puzzle"};
    }

    // 支持的地区
    static QStringList getSupportedRegions() {
        return {"asia", "europe", "america"};
    }

    // 服务器偏好
    static QStringList getServerPreferences() {
        return {"low_latency", "high_performance", "balanced"};
    }

signals:
    /**
     * @brief 游戏服务器列表接收成功信号（传统API）
     */
    void gameServersReceived(const QList<GameServer> &servers, const ServerSummary &summary);
    
    /**
     * @brief 服务发现完成信号（服务发现API）
     * @param services 发现的服务列表
     * @param gameType 查询的游戏类型
     * @param queryInfo 查询信息
     */
    void gameServicesDiscovered(const QList<GameServiceInfo> &services, const QString &gameType, const QJsonObject &queryInfo);
    
    /**
     * @brief 游戏加入成功信号
     */
    void gameJoinSucceeded(const GameLoginResult &result);
    
    /**
     * @brief 游戏加入失败信号
     */
    void gameJoinFailed(const QString &error);
    
    /**
     * @brief 请求失败信号
     */
    void requestFailed(const QString &error);
    
    /**
     * @brief 服务发现错误信号
     */
    void serviceDiscoveryError(const QString &error, const QString &errorCode);

private slots:
    /**
     * @brief 处理传统API响应
     */
    void onApiResponse(const QString &endpoint, const ApiClient::ApiResponse &response);
    
    /**
     * @brief 处理服务发现响应
     */
    void onServicesDiscovered(const QList<GameServiceInfo> &services, const QString &gameType, const QJsonObject &queryInfo);
    
    /**
     * @brief 处理服务发现错误
     */
    void onServiceDiscoveryError(const QString &error, const QString &errorCode);

private:
    // === 核心组件 ===
    ApiClient *m_apiClient;                          ///< API客户端
    GameServiceDiscovery *m_serviceDiscovery;        ///< 服务发现客户端
    QString m_pendingOperation;                      ///< 当前待处理操作
    
    // === 解析方法 ===
    /**
     * @brief 解析游戏服务器信息
     */
    GameServer parseGameServer(const QJsonObject &data) const;
    
    /**
     * @brief 解析游戏登录结果
     */
    GameLoginResult parseGameLoginResult(const QJsonObject &data) const;
    
    /**
     * @brief 解析服务器汇总信息
     */
    ServerSummary parseServerSummary(const QJsonObject &data) const;
    
    /**
     * @brief 将服务发现结果转换为游戏服务器信息
     * @param serviceInfo 服务发现信息
     * @return 游戏服务器信息
     */
    GameServer convertServiceToGameServer(const GameServiceInfo &serviceInfo) const;
    
    /**
     * @brief 从服务列表生成汇总信息
     * @param services 服务列表
     * @return 服务器汇总信息
     */
    ServerSummary generateSummaryFromServices(const QList<GameServiceInfo> &services) const;
};

#endif // GAMESERVICE_H
